GitLab CI Syntax and Variables Summary

I have recently started researching GitLab CI again. Although I began this work a while ago, the intermittent nature of my study meant I often had to re-look up the purpose of certain syntax. I decided to have Claude help me organize some common syntax for easy future reference.

Basic Structure

The GitLab CI configuration file is .gitlab-ci.yml, which defines the tasks your project should execute in the GitLab CI pipeline.

General file naming conventions:

Main CI/CD configuration file: .gitlab-ci.yml (fixed name).
Included files (includes): Usually follow the .gitlab-ci-*.yml format, for example:
- .gitlab-ci-deploy.yml
- .gitlab-ci-build.yml
- .gitlab-ci-test.yml

Stages

Stages define the execution order of jobs:

yaml

stages:
  - build
  - test
  - deploy

All jobs within a stage run in parallel, and all must succeed before moving to the next stage.

Common stage names (in order of execution):

build - Build stage.
test - Test stage.
quality - Code quality checks.
security - Security checks.
publish - Publish to registry.
deploy - Deploy to environment.
notify - Notifications.
cleanup - Resource cleanup.

Jobs

Jobs are the units that actually perform the work:

yaml

build-job:
  stage: build
  script:
    - echo "Building the app..."
    - mkdir build
    - cd build
    - cmake ..

Naming convention: Jobs usually follow the "action-object-environment" pattern, for example:

build-app
test-api
deploy-staging

Rules

Rules define the conditions under which a job is executed:

yaml

test-job:
  stage: test
  script:
    - echo "Running tests..."
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - when: never

Rules are evaluated in order. When a rule matches, the when value of that rule is applied to determine if the job should run.

Only/Except

This is older syntax but still valid. It restricts job execution based on branches or tags:

yaml

deploy-job:
  stage: deploy
  script:
    - echo "Deploying application..."
  only:
    - main
    - tags

TIP

GitLab officially recommends using rules instead of only/except because rules provides more flexibility and control. The equivalent rules syntax is:

yaml

deploy-job:
  stage: deploy
  script:
    - echo "Deploying application..."
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

Variables

You can define global or job-specific variables:

yaml

variables:
  GLOBAL_VAR: "global value"

test-job:
  variables:
    JOB_SPECIFIC_VAR: "job specific value"
  script:
    - echo $GLOBAL_VAR
    - echo $JOB_SPECIFIC_VAR

Naming convention: Variables are typically all uppercase with underscores, for example:

APP_VERSION
DOCKER_IMAGE_NAME
DATABASE_URL

TIP

When using variables in GitLab CI, you can reference them using $VARIABLE_NAME or ${VARIABLE_NAME} syntax. When a variable name needs to be concatenated with other text, use the ${VARIABLE_NAME} syntax to explicitly define the scope of the variable name and avoid parsing errors.

Before Script / After Script

Scripts to be executed before and after a job runs:

yaml

default:
  before_script:
    - echo "Before script section"
  after_script:
    - echo "After script section"

job1:
  script:
    - echo "My script"

Cache

Used to store and reuse files between builds:

yaml

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/

Naming convention: Cache keys usually use a combination of variables:

${CI_COMMIT_REF_SLUG} - Based on branch.
${CI_JOB_NAME}-${CI_COMMIT_REF_SLUG} - Based on job and branch.

Artifacts

Files generated after jobs complete, which can be downloaded or used by subsequent jobs:

yaml

build-job:
  stage: build
  script:
    - echo "Creating artifacts..."
    - mkdir -p build/
    - touch build/info.txt
  artifacts:
    paths:
      - build/
    expire_in: 1 week

Dependencies

Defines which jobs' artifacts a job should use:

yaml

test-job:
  stage: test
  dependencies:
    - build-job
  script:
    - echo "Testing with artifacts from build-job"

Workflow

Workflow controls the execution conditions of the entire pipeline. Unlike job-level rules, workflow:rules determine whether to create the pipeline at all. If no rules match or all rules evaluate to when:never, the entire pipeline will not execute.

Basic Syntax

yaml

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_MERGE_REQUEST_IID
      when: always
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

Meaning of the above example:

Always run the pipeline when pushing to the main branch.
Always run the pipeline when there is a merge request.
Always run the pipeline when there is a tag.
Do not run the pipeline in other cases.

Naming the Pipeline

You can specify a name for the pipeline, which is displayed in the GitLab interface:

yaml

workflow:
  name: "Main Pipeline"

You can also use variables in the name:

yaml

workflow:
  name: "$CI_COMMIT_REF_NAME deployment"

Rule Conditions

Workflow rules support the same conditions as job rules:

yaml

workflow:
  rules:
    # Run only on scheduled pipelines
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: always

    # Run only on pushes to specific branches
    - if: $CI_COMMIT_BRANCH == "release/*"
      when: always

    # Run based on file changes
    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TITLE =~ /docs:/
      changes:
        - docs/**/*
      when: always

    # Run when the configuration file itself is modified
    - changes:
      - .gitlab-ci.yml
      when: always

    # Set variables
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        IS_DEVELOPMENT: "true"
      when: always

    # Default case
    - when: never

Practical Examples

Decide whether to run the pipeline based on the commit message:

yaml

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /\[skip ci\]/
      when: never
    - if: $CI_COMMIT_TITLE =~ /\[run ci\]/
      when: always
    - when: on_success

Decide to run different pipelines based on project path changes:

yaml

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - frontend/**/*
      variables:
        PIPELINE_TYPE: "frontend"
      when: always
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - backend/**/*
      variables:
        PIPELINE_TYPE: "backend"
      when: always
    - when: never

Automatically run the pipeline only during working hours:

yaml

workflow:
  rules:
    # Workdays (Monday to Friday)
    - if: $CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH == "main"
      when: always
    # Working hours (9:00 - 18:00)
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main" && $HOUR >= 9 && $HOUR < 18
      when: always
    # Manual trigger required outside working hours
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
      allow_failure: true
    - when: never

Notes

workflow:rules are global and affect the entire pipeline.
If workflow:rules is not set, GitLab uses default rules, meaning all pushes and merge requests trigger a pipeline.
When using when:never in workflow:rules, the entire pipeline will not execute, rather than just skipping the rule.
Workflow rules are evaluated in order; once a matching rule is found, evaluation stops.
Variables set in the workflow can be accessed by all jobs.

Needs

Allows a job to run immediately after specified jobs complete, without waiting for the entire stage to finish:

yaml

job2:
  stage: test
  needs:
    - job1
  script:
    - echo "This job runs after job1, even if they're in the same stage"

Services

Defines an additional Docker container, usually used to provide services like databases:

yaml

test:
  services:
    - postgres:13
  script:
    - echo "Testing with Postgres service"

Includes

Import configuration from other files:

yaml

include:
  - local: '/templates/ci-template.yml'
  - project: 'my-group/my-project'
    file: '/templates/ci-template.yml'
  - template: Auto-DevOps.gitlab-ci.yml

Templates

Use YAML anchors and aliases to create reusable templates:

yaml

# Define template (jobs starting with a dot will not be executed)
.build_template: &build_definition
  stage: build
  script:
    - echo "Building using template"
  tags:
    - docker

# Use template
build_job1:
  <<: *build_definition
  script:
    - echo "Building job 1"
    - make build

# Extend template
build_job2:
  <<: *build_definition
  script:
    - echo "Building job 2"
    - make special-build
  variables:
    BUILD_TYPE: "special"

Naming convention:

Template job names start with a dot, e.g., .build_template.
Template anchors usually use _definition or _template suffixes.

Predefined Environment Variables List

The following content is excerpted from the Predefined CI/CD variables reference. I used Claude to help translate it into Chinese for my own reference.

Scope Description

Scope	Description
Pre-pipeline	Variables that exist before the pipeline is created; available to all jobs.
Pipeline	Variables generated after the pipeline is created; available to all jobs.
Job-only	Variables available only in the execution environment of a specific job.

ChatOps and Basic CI Variables

Variable	Scope	Description
CHAT_CHANNEL	Pipeline	The chat channel that triggered the ChatOps command.
CHAT_INPUT	Pipeline	Additional parameters passed with the ChatOps command.
CHAT_USER_ID	Pipeline	The user ID of the user who triggered the ChatOps command in the chat service.
CI	Pre-pipeline	Available in all CI/CD jobs. True when available.
CI_API_V4_URL	Pre-pipeline	GitLab API v4 root URL.
CI_API_GRAPHQL_URL	Pre-pipeline	GitLab API GraphQL root URL. Introduced in GitLab 15.11.
CI_DEBUG_TRACE	Pipeline	True if debug logging (tracing) is enabled.
CI_DEBUG_SERVICES	Pipeline	True if service container logging is enabled. Introduced in GitLab 15.7. Requires GitLab Runner 15.7.
GITLAB_CI	Pre-pipeline	Available in all CI/CD jobs. True when available.
GITLAB_FEATURES	Pre-pipeline	Comma-separated list of licensed features available to the GitLab instance and license.

Variable	Scope	Description
CI_BUILDS_DIR	Job-only	Top-level directory where builds are executed.
CI_COMMIT_AUTHOR	Pre-pipeline	Author of the commit, in the format Name <email>.
CI_COMMIT_BEFORE_SHA	Pre-pipeline	The previous latest commit on the branch or tag. Always 0000000000000000000000000000000000000000 in merge request pipelines, scheduled pipelines, the first commit of a branch or tag, or manual pipelines.
CI_COMMIT_BRANCH	Pre-pipeline	The branch name of the commit. Available in branch pipelines, including default branch pipelines. Not available in merge request or tag pipelines.
CI_COMMIT_DESCRIPTION	Pre-pipeline	The description of the commit. The message excluding the first line if the title is less than 100 characters.
CI_COMMIT_MESSAGE	Pre-pipeline	The full commit message.
CI_COMMIT_REF_NAME	Pre-pipeline	The branch or tag name for which the project is built.
CI_COMMIT_REF_PROTECTED	Pre-pipeline	True if the job is running for a protected reference, false otherwise.
CI_COMMIT_REF_SLUG	Pre-pipeline	Lowercase version of CI_COMMIT_REF_NAME, truncated to 63 bytes, with all characters except 0-9 and a-z replaced by -. No leading/trailing -. Used for URLs, hostnames, and domain names.
CI_COMMIT_SHA	Pre-pipeline	The commit revision for which the project is built.
CI_COMMIT_SHORT_SHA	Pre-pipeline	The first eight characters of CI_COMMIT_SHA.
CI_COMMIT_TAG	Pre-pipeline	The commit tag name. Available only in tag pipelines.
CI_COMMIT_TAG_MESSAGE	Pre-pipeline	The commit tag message. Available only in tag pipelines. Introduced in GitLab 15.5.
CI_COMMIT_TIMESTAMP	Pre-pipeline	The commit timestamp in ISO 8601 format. For example, 2022-01-31T16:47:55Z. Defaults to UTC.
CI_COMMIT_TITLE	Pre-pipeline	The title of the commit. The full first line of the message.
CI_OPEN_MERGE_REQUESTS	Pre-pipeline	Comma-separated list of up to four merge requests using the current branch and project as the source. Available only in branch and merge request pipelines if the branch has associated merge requests. For example, gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11.

Variable	Scope	Description
CI_CONFIG_PATH	Pre-pipeline	Path to the CI/CD configuration file. Defaults to .gitlab-ci.yml.
CI_CONCURRENT_ID	Job-only	Unique ID for build execution in a single runner.
CI_CONCURRENT_PROJECT_ID	Job-only	Unique ID for build execution in a single runner and project.
CI_DEFAULT_BRANCH	Pre-pipeline	The default branch name of the project.
CI_PROJECT_DIR	Job-only	Full path where the repository is cloned and the job is executed. If the GitLab Runner builds_dir parameter is set, this variable is relative to the builds_dir value. For more information, see advanced GitLab Runner configuration.
CI_REPOSITORY_URL	Job-only	Full path to clone the repository using the CI/CD job token (HTTP), in the format https://gitlab-ci-token:[email protected]/my-group/my-project.git.

Variable	Scope	Description
CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX	Pre-pipeline	Direct group image prefix for pulling images through the dependency proxy.
CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX	Pre-pipeline	Top-level group image prefix for pulling images through the dependency proxy.
CI_DEPENDENCY_PROXY_PASSWORD	Pipeline	Password for pulling images through the dependency proxy.
CI_DEPENDENCY_PROXY_SERVER	Pre-pipeline	Server for logging into the dependency proxy. This variable is equivalent to $C I_{S} E R V E R_{H} O S T :$ CI_SERVER_PORT.
CI_DEPENDENCY_PROXY_USER	Pipeline	Username for pulling images through the dependency proxy.

Variable	Scope	Description
CI_DEPLOY_FREEZE	Pre-pipeline	Available only when the pipeline runs during a deployment freeze window. True when available.
CI_DEPLOY_PASSWORD	Job-only	Authentication password for the GitLab Deploy Token, if the project has one.
CI_DEPLOY_USER	Job-only	Authentication username for the GitLab Deploy Token, if the project has one.
CI_DISPOSABLE_ENVIRONMENT	Pipeline	Available only when the job runs in a disposable environment (an environment created only for this job and disposed of after execution - all executors except shell and ssh). True when available.
CI_ENVIRONMENT_NAME	Pipeline	The environment name for this job. Available if environment:name is set.
CI_ENVIRONMENT_SLUG	Pipeline	Simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Available if environment:name is set. The slug is truncated to 24 characters. For uppercase environment names, a random suffix is automatically added.
CI_ENVIRONMENT_URL	Pipeline	The environment URL for this job. Available if environment:url is set.
CI_ENVIRONMENT_ACTION	Pipeline	The action note specified for this job's environment. Available if environment:action is set. Can be start, prepare, or stop.
CI_ENVIRONMENT_TIER	Pipeline	The deployment tier for this job's environment.
CI_KUBERNETES_ACTIVE	Pre-pipeline	Available only when the pipeline has a Kubernetes cluster available for deployment. True when available.
CI_RELEASE_DESCRIPTION	Pipeline	The description of the release. Available only in tag pipelines. The description length is limited to the first 1024 characters. Introduced in GitLab 15.5.
KUBECONFIG	Pipeline	Path to the kubeconfig file containing environment settings for each shared agent connection. Available only when the GitLab agent is authorized to access the project.

Variable	Scope	Description
CI_GITLAB_FIPS_MODE	Pre-pipeline	Available only when FIPS mode is enabled in the GitLab instance. True when available.
CI_HAS_OPEN_REQUIREMENTS	Pipeline	Available only when the pipeline's project has open requirements. True when available.
CI_JOB_GROUP_NAME	Pipeline	Shared name for the job group when using parallel or manual grouped jobs. For example, if the job name is rspec:test: [ruby, ubuntu], CI_JOB_GROUP_NAME is rspec:test. Otherwise, it is the same as CI_JOB_NAME. Introduced in GitLab 17.10.
CI_JOB_ID	Job-only	Internal ID of the job, unique across all jobs in the GitLab instance.
CI_JOB_IMAGE	Pipeline	The Docker image name used to execute the job.
CI_JOB_MANUAL	Pipeline	Available only when the job is started manually. True when available.
CI_JOB_NAME	Pipeline	The name of the job.
CI_JOB_NAME_SLUG	Pipeline	Lowercase version of CI_JOB_NAME, truncated to 63 bytes, with all characters except 0-9 and a-z replaced by -. No leading/trailing -. Used for paths. Introduced in GitLab 15.4.
CI_JOB_STAGE	Pipeline	The stage name of the job.
CI_JOB_STATUS	Job-only	The status of the job when executing each runner stage. Used with after_script. Can be success, failed, or canceled.
CI_JOB_TIMEOUT	Job-only	Job timeout in seconds. Introduced in GitLab 15.7. Requires GitLab Runner 15.7.
CI_JOB_TOKEN	Job-only	Token used to authenticate certain API endpoints. The token is valid during the job execution.
CI_JOB_URL	Job-only	URL for job details.
CI_JOB_STARTED_AT	Job-only	Date and time the job started, in ISO 8601 format. For example, 2022-01-31T16:47:55Z. Defaults to UTC.
CI_NODE_INDEX	Pipeline	Index of the job in the job set. Available only when the job uses parallel.
CI_NODE_TOTAL	Pipeline	Total number of parallel instances for this job. Set to 1 if the job does not use parallel.

Variable	Scope	Description
CI_PAGES_DOMAIN	Pre-pipeline	The instance domain hosting GitLab Pages, excluding the namespace subdomain. To use the full hostname, use CI_PAGES_HOSTNAME.
CI_PAGES_HOSTNAME	Job-only	The full hostname where Pages are deployed.
CI_PAGES_URL	Job-only	The URL of the GitLab Pages site. Always a subdomain of CI_PAGES_DOMAIN. In GitLab 17.9 and later, when path_prefix is specified, the value includes the path_prefix.

Variable	Scope	Description
CI_PIPELINE_ID	Job-only	Instance-level ID of the current pipeline. This ID is unique across all projects in the GitLab instance.
CI_PIPELINE_IID	Pipeline	Project-level IID (internal ID) of the current pipeline. This ID is unique only within the current project.
CI_PIPELINE_SOURCE	Pre-pipeline	How the pipeline was triggered. The value can be one of the pipeline sources.
CI_PIPELINE_TRIGGERED	Pipeline	True if the job was triggered.
CI_PIPELINE_URL	Job-only	URL for pipeline details.
CI_PIPELINE_CREATED_AT	Pre-pipeline	Date and time the pipeline was created, in ISO 8601 format. For example, 2022-01-31T16:47:55Z. Defaults to UTC.
CI_PIPELINE_NAME	Pre-pipeline	The pipeline name defined in workflow:name. Introduced in GitLab 16.3.
CI_PIPELINE_SCHEDULE_DESCRIPTION	Pre-pipeline	Description of the pipeline schedule. Available only in scheduled pipelines. Introduced in GitLab 17.8.

Variable	Scope	Description
CI_PROJECT_ID	Pre-pipeline	ID of the current project. This ID is unique across all projects in the GitLab instance.
CI_PROJECT_NAME	Pre-pipeline	Name of the project directory. For example, if the project URL is gitlab.example.com/group-name/project-1, CI_PROJECT_NAME is project-1.
CI_PROJECT_NAMESPACE	Pre-pipeline	Project namespace (username or group name) of the job.
CI_PROJECT_NAMESPACE_ID	Pre-pipeline	Project namespace ID of the job. Introduced in GitLab 15.7.
CI_PROJECT_NAMESPACE_SLUG	Pre-pipeline	Lowercase version of $CI_PROJECT_NAMESPACE, with characters that are not a-z or 0-9 replaced by - and truncated to 63 bytes.
CI_PROJECT_PATH_SLUG	Pre-pipeline	Lowercase version of $CI_PROJECT_PATH, with characters that are not a-z or 0-9 replaced by - and truncated to 63 bytes. Used for URLs and domain names.
CI_PROJECT_PATH	Pre-pipeline	Project namespace including the project name.
CI_PROJECT_REPOSITORY_LANGUAGES	Pre-pipeline	Comma-separated, lowercase list of languages used in the repository. For example, ruby,javascript,html,css. The maximum number of languages is limited to 5. There is an issue proposing to increase the limit.
CI_PROJECT_ROOT_NAMESPACE	Pre-pipeline	Root project namespace (username or group name) of the job. For example, if CI_PROJECT_NAMESPACE is root-group/child-group/grandchild-group, CI_PROJECT_ROOT_NAMESPACE is root-group.
CI_PROJECT_TITLE	Pre-pipeline	Human-readable project name displayed in the GitLab Web interface.
CI_PROJECT_DESCRIPTION	Pre-pipeline	Project description displayed in the GitLab Web interface. Introduced in GitLab 15.1.
CI_PROJECT_URL	Pre-pipeline	HTTP(S) URL of the project.
CI_PROJECT_VISIBILITY	Pre-pipeline	Project visibility. Can be internal, private, or public.
CI_PROJECT_CLASSIFICATION_LABEL	Pre-pipeline	External authorization classification label for the project.

Variable	Scope	Description
CI_REGISTRY	Pre-pipeline	URL of the container registry server, in the format <host>[:<port>]. For example: registry.gitlab.example.com. Available only if the GitLab instance has the container registry enabled.
CI_REGISTRY_IMAGE	Pre-pipeline	Base URL of the container registry for pushing, pulling, or tagging project images, in the format <host>[:<port>]/<project_full_path>. For example: registry.gitlab.example.com/my_group/my_project. Image names must follow container registry naming conventions. Available only if the container registry is enabled for the project.
CI_REGISTRY_PASSWORD	Job-only	Password for pushing containers to the GitLab project's container registry. Available only if the container registry is enabled for the project. This password value is the same as CI_JOB_TOKEN and is valid only during job execution. Use CI_DEPLOY_PASSWORD for long-term registry access.
CI_REGISTRY_USER	Job-only	Username for pushing containers to the project's GitLab container registry. Available only if the container registry is enabled for the project.
CI_TEMPLATE_REGISTRY_HOST	Pre-pipeline	Registry host used by CI/CD templates. Defaults to registry.gitlab.com. Introduced in GitLab 15.3.

Variable	Scope	Description
CI_RUNNER_DESCRIPTION	Job-only	Description of the runner.
CI_RUNNER_EXECUTABLE_ARCH	Job-only	OS/architecture of the GitLab Runner executable. May differ from the executor's environment.
CI_RUNNER_ID	Job-only	Unique ID of the runner being used.
CI_RUNNER_REVISION	Job-only	Revision of the runner executing the job.
CI_RUNNER_SHORT_TOKEN	Job-only	Unique ID of the runner used to authenticate new job requests. The token contains a prefix; use the first 17 characters.
CI_RUNNER_TAGS	Job-only	JSON array of runner tags. For example ["tag_1", "tag_2"].
CI_RUNNER_VERSION	Job-only	Version of the GitLab Runner executing the job.
CI_SHARED_ENVIRONMENT	Pipeline	Available only when the job runs in a shared environment (an environment that persists between CI/CD invocations, such as shell or ssh executors). True when available.

Variable	Scope	Description
CI_SERVER_FQDN	Pre-pipeline	Fully Qualified Domain Name (FQDN) of the instance. For example, gitlab.example.com:8080. Introduced in GitLab 16.10.
CI_SERVER_HOST	Pre-pipeline	Host of the GitLab instance URL, excluding protocol or port. For example, gitlab.example.com.
CI_SERVER_NAME	Pre-pipeline	Name of the CI/CD server coordinating the job.
CI_SERVER_PORT	Pre-pipeline	Port of the GitLab instance URL, excluding host or protocol. For example, 8080.
CI_SERVER_PROTOCOL	Pre-pipeline	Protocol of the GitLab instance URL, excluding host or port. For example, https.
CI_SERVER_SHELL_SSH_HOST	Pre-pipeline	SSH host of the GitLab instance, used for accessing Git repositories via SSH. For example, gitlab.com. Introduced in GitLab 15.11.
CI_SERVER_SHELL_SSH_PORT	Pre-pipeline	SSH port of the GitLab instance, used for accessing Git repositories via SSH. For example, 22. Introduced in GitLab 15.11.
CI_SERVER_REVISION	Pre-pipeline	GitLab revision that scheduled the job.
CI_SERVER_TLS_CA_FILE	Pipeline	File containing the TLS CA certificate, used to verify the GitLab server when tls-ca-file is set in the runner configuration.
CI_SERVER_TLS_CERT_FILE	Pipeline	File containing the TLS certificate, used to verify the GitLab server when tls-cert-file is set in the runner configuration.
CI_SERVER_TLS_KEY_FILE	Pipeline	File containing the TLS key, used to verify the GitLab server when tls-key-file is set in the runner configuration.
CI_SERVER_URL	Pre-pipeline	Base URL of the GitLab instance, including protocol and port. For example, https://gitlab.example.com:8080.
CI_SERVER_VERSION_MAJOR	Pre-pipeline	Major version of the GitLab instance. For example, if the GitLab version is 17.2.1, CI_SERVER_VERSION_MAJOR is 17.
CI_SERVER_VERSION_MINOR	Pre-pipeline	Minor version of the GitLab instance. For example, if the GitLab version is 17.2.1, CI_SERVER_VERSION_MINOR is 2.
CI_SERVER_VERSION_PATCH	Pre-pipeline	Patch version of the GitLab instance. For example, if the GitLab version is 17.2.1, CI_SERVER_VERSION_PATCH is 1.
CI_SERVER_VERSION	Pre-pipeline	Full version of the GitLab instance.
CI_SERVER	Job-only	Available in all CI/CD jobs. Yes when available.

Variable	Scope	Description
CI_TRIGGER_SHORT_TOKEN	Job-only	The first 4 characters of the trigger token for the current job. Available only when the pipeline is triggered by a trigger token. For example, for trigger token glptt-1234567890abcdefghij, CI_TRIGGER_SHORT_TOKEN is 1234. Introduced in GitLab 17.0.
GITLAB_USER_EMAIL	Pipeline	Email of the user who started the pipeline, unless the job is a manual job. In a manual job, the value is the email of the user who started the job.
GITLAB_USER_ID	Pipeline	Numeric ID of the user who started the pipeline, unless the job is a manual job. In a manual job, the value is the ID of the user who started the job.
GITLAB_USER_LOGIN	Pipeline	Unique username of the user who started the pipeline, unless the job is a manual job. In a manual job, the value is the username of the user who started the job.
GITLAB_USER_NAME	Pipeline	Display name of the user who started the pipeline (the full name defined by the user in profile settings), unless the job is a manual job. In a manual job, the value is the name of the user who started the job.
TRIGGER_PAYLOAD	Pipeline	Webhook data payload. Available only when the pipeline is triggered using a webhook.

Variable	Description
CI_MERGE_REQUEST_APPROVED	Approval status of the merge request. True when merge request approvals are available and the merge request has been approved.
CI_MERGE_REQUEST_ASSIGNEES	Comma-separated list of usernames assigned to the merge request. Available only if the merge request has at least one assignee.
CI_MERGE_REQUEST_DIFF_BASE_SHA	Base SHA of the merge request diff.
CI_MERGE_REQUEST_DIFF_ID	Version of the merge request diff.
CI_MERGE_REQUEST_EVENT_TYPE	Event type of the merge request. Can be detached, merged_result, or merge_train.
CI_MERGE_REQUEST_DESCRIPTION	Description of the merge request. If the description length exceeds 2700 characters, only the first 2700 characters are stored in the variable. Introduced in GitLab 16.7.
CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED	True if CI_MERGE_REQUEST_DESCRIPTION was truncated to 2700 characters because the merge request description was too long, false otherwise. Introduced in GitLab 16.8.
CI_MERGE_REQUEST_ID	Instance-level ID of the merge request. This ID is unique across all projects in the GitLab instance.
CI_MERGE_REQUEST_IID	Project-level IID (internal ID) of the merge request. This ID is unique within the current project and is the number used in the merge request URL, page title, and other visible locations.
CI_MERGE_REQUEST_LABELS	Comma-separated list of label names for the merge request. Available only if the merge request has at least one label.
CI_MERGE_REQUEST_MILESTONE	Milestone title of the merge request. Available only if the merge request has a milestone set.
CI_MERGE_REQUEST_PROJECT_ID	Project ID of the merge request.
CI_MERGE_REQUEST_PROJECT_PATH	Project path of the merge request. For example, namespace/awesome-project.
CI_MERGE_REQUEST_PROJECT_URL	Project URL of the merge request. For example, http://192.168.10.15:3000/namespace/awesome-project.
CI_MERGE_REQUEST_REF_PATH	Reference path of the merge request. For example, refs/merge-requests/1/head.
CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	Source branch name of the merge request.
CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED	True when the source branch of the merge request is protected. Introduced in GitLab 16.4.
CI_MERGE_REQUEST_SOURCE_BRANCH_SHA	HEAD SHA of the source branch of the merge request. In merge request pipelines, the variable is empty. The SHA appears only in merged result pipelines.
CI_MERGE_REQUEST_SOURCE_PROJECT_ID	Source project ID of the merge request.
CI_MERGE_REQUEST_SOURCE_PROJECT_PATH	Source project path of the merge request.
CI_MERGE_REQUEST_SOURCE_PROJECT_URL	Source project URL of the merge request.
CI_MERGE_REQUEST_SQUASH_ON_MERGE	True when the squash on merge option is set. Introduced in GitLab 16.4.
CI_MERGE_REQUEST_TARGET_BRANCH_NAME	Target branch name of the merge request.
CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED	True when the target branch of the merge request is protected. Introduced in GitLab 15.2.
CI_MERGE_REQUEST_TARGET_BRANCH_SHA	HEAD SHA of the target branch of the merge request. In merge request pipelines, the variable is empty. The SHA appears only in merged result pipelines.
CI_MERGE_REQUEST_TITLE	Title of the merge request.
CI_MERGE_REQUEST_DRAFT	True if the merge request is a draft. Introduced in GitLab 17.10.

Variable	Description
CI_EXTERNAL_PULL_REQUEST_IID	Pull request ID from GitHub.
CI_EXTERNAL_PULL_REQUEST_SOURCE_REPOSITORY	Source repository name of the pull request.
CI_EXTERNAL_PULL_REQUEST_TARGET_REPOSITORY	Target repository name of the pull request.
CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME	Source branch name of the pull request.
CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA	HEAD SHA of the source branch of the pull request.
CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME	Target branch name of the pull request.
CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA	HEAD SHA of the target branch of the pull request.
CI_EXTERNAL_PULL_REQUEST_LABELS	Comma-separated list of labels for the pull request. Available only if the merge request has at least one label.
CI_EXTERNAL_PULL_REQUEST_TITLE	Title of the pull request.
CI_EXTERNAL_PULL_REQUEST_DESCRIPTION	Description of the pull request.
CI_EXTERNAL_PULL_REQUEST_HTML_URL	HTML URL of the pull request.

Integration Variables

The following integration variables are available in jobs as "job-only" predefined variables:

Harbor

Variable	Description
HARBOR_URL	URL of the Harbor instance.
HARBOR_HOST	Hostname of the Harbor instance.
HARBOR_OCI	Harbor OCI connection settings.
HARBOR_PROJECT	Target Harbor project name.
HARBOR_USERNAME	Harbor authentication username.
HARBOR_PASSWORD	Harbor authentication password.

Apple App Store Connect

Variable	Description
APP_STORE_CONNECT_API_KEY_ISSUER_ID	Apple App Store Connect API key issuer ID.
APP_STORE_CONNECT_API_KEY_KEY_ID	Apple App Store Connect API key ID.
APP_STORE_CONNECT_API_KEY_KEY	Apple App Store Connect API key content.
APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64	Indicates whether the API key content is Base64 encoded.

Google Play

Variable	Description
SUPPLY_PACKAGE_NAME	Package name of the Android application.
SUPPLY_JSON_KEY_DATA	JSON key data for Google Play API access.

Diffblue Cover

Variable	Description
DIFFBLUE_LICENSE_KEY	License key for Diffblue Cover.
DIFFBLUE_ACCESS_TOKEN_NAME	Diffblue access token name.
DIFFBLUE_ACCESS_TOKEN	Diffblue access token.

Changelog

2025-04-07
- Initial document creation.

GitLab CI Syntax and Variables Summary ​

Basic Structure ​

Stages ​

Jobs ​

Rules ​

Only/Except ​

Variables ​

Before Script / After Script ​

Cache ​

Artifacts ​

Dependencies ​

Workflow ​

Basic Syntax ​

Naming the Pipeline ​

Rule Conditions ​

Practical Examples ​

Notes ​

Needs ​

Services ​

Includes ​

Templates ​

Predefined Environment Variables List ​

Scope Description ​

ChatOps and Basic CI Variables ​

Commit-related Variables ​

Configuration and Path-related Variables ​

Dependency Proxy-related Variables ​

Deployment and Environment-related Variables ​

Job-related Variables ​

Pages-related Variables ​

Pipeline-related Variables ​

Project-related Variables ​

Container Registry-related Variables ​

Runner-related Variables ​

Server-related Variables ​

Trigger and User-related Variables ​

Merge Request-related Variables ​

External Request-related Variables ​

Integration Variables ​

Harbor ​

Apple App Store Connect ​

Google Play ​

Diffblue Cover ​

Changelog ​

Tags

Related Notes

How to use GitLab CI in Docker

Setting up GitLab as a NuGet Package Source in Visual Studio

A Brief Introduction to Git Commit Conventions

A Brief Discussion on the Differences Between Git Merge and Rebase

GitLab CI Syntax and Variables Summary

Basic Structure

Stages

Jobs

Rules

Only/Except

Variables

Before Script / After Script

Cache

Artifacts

Dependencies

Workflow

Basic Syntax

Naming the Pipeline

Rule Conditions

Practical Examples

Notes

Needs

Services

Includes

Templates

Predefined Environment Variables List

Scope Description

ChatOps and Basic CI Variables

Commit-related Variables

Configuration and Path-related Variables

Dependency Proxy-related Variables

Deployment and Environment-related Variables

Job-related Variables

Pages-related Variables

Pipeline-related Variables

Project-related Variables

Container Registry-related Variables

Runner-related Variables

Server-related Variables

Trigger and User-related Variables

Merge Request-related Variables

External Request-related Variables

Integration Variables

Harbor

Apple App Store Connect

Google Play

Diffblue Cover

Changelog